cls-bluebird

What is cls-bluebird?

The cls-bluebird npm package is a utility that integrates continuation-local storage (CLS) with the Bluebird promise library. This allows you to maintain context across asynchronous operations, which is particularly useful for things like request tracing, logging, and managing user sessions.

What are cls-bluebird's main functionalities?

Integrate CLS with Bluebird

This feature allows you to integrate CLS with Bluebird promises. The code sample demonstrates how to create a namespace, integrate it with Bluebird, and maintain context across asynchronous operations.

const cls = require('cls-hooked');
const ns = cls.createNamespace('myNamespace');
const Promise = require('bluebird');
require('cls-bluebird')(ns, Promise);

ns.run(() => {
  ns.set('key', 'value');
  Promise.resolve().then(() => {
    console.log(ns.get('key')); // Outputs: 'value'
  });
});

Maintain context in nested promises

This feature ensures that the context is maintained even in nested promises. The code sample shows how the context set in the outer promise is accessible in the inner promise.

const cls = require('cls-hooked');
const ns = cls.createNamespace('myNamespace');
const Promise = require('bluebird');
require('cls-bluebird')(ns, Promise);

ns.run(() => {
  ns.set('key', 'value');
  Promise.resolve().then(() => {
    return Promise.resolve().then(() => {
      console.log(ns.get('key')); // Outputs: 'value'
    });
  });
});

Other packages similar to cls-bluebird

cls-hooked

cls-hooked is a continuation-local storage library that works with async/await and other modern JavaScript features. Unlike cls-bluebird, it does not specifically integrate with Bluebird but can be used with any promise library.

async_hooks

async_hooks is a core Node.js module that provides an API to track asynchronous resources. It is more low-level compared to cls-bluebird and requires more manual setup but offers greater flexibility and is not limited to any specific promise library.

README

continuation-local-storage support for bluebird promises

Patch bluebird for continuation-local-storage support.

Current Status

Currently works with bluebird v2.x only. But bluebird v3.x support coming soon!

Usage

clsBluebird( ns [, Promise] )

var cls = require('continuation-local-storage');
var ns = cls.createNamespace('myNamespace');

var Promise = require('bluebird');
var clsBluebird = require('cls-bluebird');

clsBluebird( ns );
// Promise is now patched to maintain CLS context

The above patches the "global" instance of bluebird. So anywhere else in the same app that calls require('bluebird') will get the patched version (assuming npm resolves to the same file).

Patching a particular instance of Bluebird

To patch a particular instance of bluebird:

var Promise = require('bluebird');
var clsBluebird = require('cls-bluebird');

clsBluebird( ns, Promise );

This is a more robust approach.

Nature of patching

Combining CLS and promises is a slightly tricky business. There are 3 different conventions one could use (see this issue for more detail).

cls-bluebird follows the convention of binding .then() callbacks to the context in which .then() is called.

var promise;
ns.run(function() {
    ns.set('foo', 123);
    promise = Promise.resolve();
});

ns.run(function() {
    ns.set('foo', 456);
    promise.then(print);
});

function print() {
    console.log(ns.get('foo'));
}

// this outputs '456' (the value of `foo` at the time `.then()` was called)

Tests

Use npm test to run the tests.

The tests require a Redis server to be up and running on localhost on the standard port.

Work is underway to expand the tests and remove the dependence on Redis.

Changelog

See changelog.md

Issues

If you discover a bug, please raise an issue on Github. https://github.com/TimBeyer/cls-bluebird/issues

Contribution

Pull requests are very welcome. Please:

• ensure all tests pass before submitting PR
• add an entry to changelog
• add tests for new features
• document new functionality/API additions in README

Changelog

1.1.3

• Improved validation that ns argument is a namespace
• Add npm keywords